/*  ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** 
*   Copyright 2014 Jan-Marwin Wollschläger                                   *
*                                                                            *
*   Licensed under the Apache License, Version 2.0 (the "License");          *
*   you may not use this file except in compliance with the License.         *
*   You may obtain a copy of the License at                                  *
*                                                                            *
*       http://www.apache.org/licenses/LICENSE-2.0                           *
*                                                                            *
*   Unless required by applicable law or agreed to in writing, software      *
*   distributed under the License is distributed on an "AS IS" BASIS,        *
*   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
*   See the License for the specific language governing permissions and      *
*   limitations under the License.                                           *
** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **   */  
import java.util.ArrayList;

/**
 * The interface all Molecules should confer to.
 *
 * @author Jan-Marwin Wollschläger
 * @version 0.1
 **/
public interface IMolecule
{
   /**
   * @return Returns the atoms contained in this molecule as ArrayList of IAtom instances.
   **/
   public ArrayList<IAtom> getAtoms();
  
   /**
   * @return Returns a list of all bonds contained in this molecule as ArrayList of IBond
   * instances.
   **/
   public ArrayList<IBond> getBonds();
   
   /**
   * Returns the atom with the specified index
   * @param atomIndex The index of the atom in the ArrayList atoms of this IMolecule instance.
   **/
   public IAtom getAtom(int atomIndex);
   
   /**
   * Returns the bond with the specified index
   * @param bondIndex The index of the bond in the ArrayList bonds of this IMolecule instance.
   **/
   public IBond getBond(int bondIndex);
  
   /**
   * @param atoms The IAtom instances - e.g. atoms - of this molecule.
   **/
   public void setAtoms(ArrayList<IAtom> atoms);
   
   /**
   * @param bonds The Bonds for this molecule instance that link the atoms with one another.
   **/
   public void setBonds(ArrayList<IBond> bonds);
   
   /**
   *  @param atomToAdd The atom to add to the list of atoms contained in this molecule. 
   **/
   public void addAtom(IAtom atomToAdd);
  
   /**
   * @param bondToAdd The bond to add to the list of bonds contained in this molecule.
   **/   
   public void addBond(IBond bondToAdd);
   
   /**
   * Joins (or connects) two molecules at the specified atoms. It is
   * possible that fstMolecule == sndMolecule. In this case, just a bond
   * is added connecting the atoms fstAtom and sndAtom. If on the other
   * hand fstMolecule != sndMolecule, so the two specified molecules
   * differ from one another, both molecules will be joined to a new
   * IMolecule which will be the result of this method call.
   * @param fstAtom The atom contained in fstMolecule to perform the
   * joining operation at.
   * @param sndAtom The atom contained in sndMolecule where to perform
   * the joining operation at.
   * @param fstMolecule The first molecule to join with the second.
   * @param sndMolecule The second molecule to join with the first.
   * @return The joined molecule will be returned as an IMolecule
   * instance. 
   **/
   public IMolecule join(IAtom fstAtom, IAtom sndAtom,  
						   IMolecule fstMolecule,  
						   IMolecule sndMolecule);
   /**
   * This method returns the atoms of this molecule instance that are 
   * adjacent to the specified IAtom instance.
   * @param atom The atom to get the adjacent atoms of.
   * @return The list of adjacent atoms as ArrayList<IAtom>. 
   **/
   public ArrayList<IAtom> getAdjacentAtoms(IAtom atom);
   
   
   /**
   * Returns true if the specified atom is part of this molecule,
   * returns false otherwise.
   * @param atom The atom to check.
   * @return True if atom is contained in this instance, false
   * otherwise.
   */
   public boolean containsAtom(IAtom atom);
   
   
   /**
   * Returns true, if this atom label is implicit, e.g. the atom label
   * or 'atom symbol' is not to be displayed. An example for this 
   * are carbon atoms which are generally not explicitly denoted by
   * their respective symbol ('C').
   * 
   * @param whichAtom The atom for which to check if it is implicit.
   **/
   public boolean isAtomImplicit(IAtom whichAtom);
   
   /**
   * Computes the number of atoms of this instance.
   * @return The number of atoms of this instance as an integer.
   */
   public int getAtomCount();
   
   
   /**
   * Computes the number of bonds of this instance.
   * @return The number of bonds of this instance as an integer.
   */
   public int getBondCount();
}


